%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                       Legal Notice                            %
%                                                               %
% This document is copyright by Olaf Kirch, okir@monad.swb.de   %
%                                                               %
% For copying conditions, please refer to the file COPYING.     %
%                                                               %
% The author is not liable for any damages, direct or indirect, %
% resulting from the use of information provided in this        %
% document.                                                     %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% When viewing this document with vi on an 80-columns screen,   %
% do a ':se nonumber' first.                                    %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% This may vary...
\def\smailboxdir{\file{/var/spool/mail}}
%% Note that smaillib is used verbatim in some examples.
\def\smaillib{\file{/usr/lib/smail}}
\def\smailspool{\file{/var/spool/smail}}


\chapter{Getting \prog{smail} Up and Running}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Initial smail setup                                           %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail}
\index{configuring!smail@\prog{smail}|see {\prog{smail}}}
\index{smail@\prog{smail}|(}

This chapter will give you a quick introduction to setting up \prog{smail},
and an overview of the functionality it provides. Although \prog{smail}
is largely compatible with \prog{sendmail} in its behaviour, their
configuration files are completely different.


\index{smail@\prog{smail}!config file@\file{config} file}
The main configuration file is the \smaillib\file{/config}.  You always
have to edit this file to reflect values specific to your site. If you
are only a UUCP leaf site, you will have relatively little else to do,
ever.  Other files that configure routing and transport options may also
be used; they will be dealt with briefly, too.


\index{mail!queue}
By default, \prog{smail} processes and delivers all incoming mail
immediately. If you have relatively high traffic, you may instead have
\prog{smail} collect all messages in the so-called \emph{queue}, and
process it at regular intervals only.


\index{mail!daemon}
When handling mail within a TCP/IP network, \prog{smail} is frequently
run in daemon mode: at system boot time, it is invoked from
\file{rc.inet2}, and puts itself in the background where it waits for
incoming TCP connections on the SMTP port (usually port~25).  This is
very beneficial whenever you expect to have a significant amount of
traffic, because \prog{smail} isn't started up separately for every
incoming connection. The alternative would be to have \prog{inetd}
manage the SMTP port, and have it spawn \prog{smail} whenever there is a
connection on this port.


\index{smail@\prog{smail}!utilities}
\prog{smail} has a lot a flags that control it behavior; describing
them in detail here wouldn't make help you much. Fortunately,
\prog{smail} supports a number of standard modes of operation that are
enabled when you invoke it by a special command name, like \prog{rmail},
or \prog{smtpd}.  Usually, these aliases are symbolic links to the
\prog{smail} binary itself. We will encounter most of them when
discussing the various features of \prog{smail}.


There are two links to \prog{smail} you should have under all
circumstances; namely \prog{/usr/bin/rmail} and
\prog{/usr/sbin/sendmail}.\footnote{
 This is the new standard location of \prog{sendmail} according to the
 \linux{} File System Standard. Another common location is \file{/usr/lib}.
}  When you compose and send a mail message with a user agent like
\prog{elm}, the message will be piped into \prog{rmail} for delivery,
with the recipient list given to it on the command line. The same
happens with mail coming in via UUCP. Some versions of \prog{elm},
however, invoke \prog{/usr/sbin/sendmail} instead of \prog{rmail}, so you
need both of them.  For example, if you keep \prog{smail} in
\file{/usr/local/bin}, type the following at the shell prompt:


\begin{tscreen}
\# ln -s /usr/local/bin/smail /usr/bin/rmail    \\
\# ln -s /usr/local/bin/smail /usr/sbin/sendmail
\end{tscreen}


% There are, however, a number of other names \prog{smail} may be linked
% to. Among them is \prog{rsmtp}, which is analoguous to \prog{rmail}, but
% is for receiving SMTP batches (see section~\ref{smail.uucp}).
% For use in a TCP/IP network, you may also invoke it as \keyword{smtpd},
% which makes it act as SMTP server. When invoked  as \keyword{sendmail},
% it behaves in a way compatible with the original Berkeley \keyword{sendmail}.
% For queue operations, \prog{smail} also understands the names \prog{runq}
% and \prog{mailq}, which will be explained in section~\ref{smail.queue}.


If you want to dig further into the details of configuring \prog{smail},
please refer to the manual pages \prog{smail(1)} and  \prog{smail(5)}.
If it isn't included in your favorite \linux{} distribution, you can get
it from the source to \prog{smail}.



\section{UUCP Setup}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.simple}
\index{smail@\prog{smail}!UUCP|(}
\index{smail@\prog{smail}!BSMTP}
\index{UUCP!using smail@using \prog{smail}}
\index{configuring!UUCP mail}

To use \prog{smail} in a UUCP-only environment, the basic installation
is rather simple. First, you must make sure you have the two symbolic
links to \prog{rmail} and \prog{sendmail} mentioned above. If you expect
to receive SMTP batches from other sites, you also have to make
\prog{rsmtp} a link to \prog{smail}.


\index{smail@\prog{smail}!config file@\file{config} file|(}
In Vince Skahan's \prog{smail} distribution, you will find a sample
configuration file. It is named \file{config.sample} and resides in
\smaillib. You have to copy it to \file{config} and edit it to reflect
values specific to your site.


Assume your site is named \keyword{swim.twobirds.com}, and is registered
in the UUCP maps as \keyword{swim}. Your smarthost is \keyword{ulysses}.
Then your \file{config} file should look like this:


\begin{tscreen}
\begin{verbatim}
#
# Our domain names
visible_domain=two.birds:uucp
#
# Our name on outgoing mails
visible_name=swim.twobirds.com
#
# Use this as uucp-name as well
uucp_name=swim.twobirds.com
#
# Our smarthost
smart_host=ulysses
\end{verbatim}
\end{tscreen}


\index{smail@\prog{smail}!local hostnames}
The first statement tells \prog{smail} about the domains your site
belongs to.  Insert their names here, separated by colons. If your site
name is registered in the UUCP maps, you should also add \keyword{uucp}.
When being handed a mail message, \prog{smail} determines your host's
name using the \func{hostname(2)} system call, and checks the
recipient's address against this hostname, tacking on all names from
this list in turn. If the address matches any of these names, or
the unqualified hostname, the recipient is considered local, and
\prog{smail} attempts to deliver the message to a user or alias on the
local host. Otherwise, the recipient is considered remote, and delivery
to the destination host is attempted.


\keyword{visible\_name} should contain a single, fully qualified domain name
of your site that you want to use on outgoing mails. This name is used
when generating the sender's address on all outgoing mail.  You must
make sure to use a name that \prog{smail} recognizes as referring to the
local host (i.e. the hostname with one of the domains listed in the
\keyword{visible\_domain} attribute). Otherwise, replies to your mails
will bounce off your site.


\index{smail@\prog{smail}!routing!smart-host}
The last statement sets the path used for smart-host routing (described
in section~\ref{mail.routing}). With this sample setup, \prog{smail}
will forward any mail for remote addresses to the smart host. The path
specified in the \keyword{smart\_path} attribute will be used as a route
to the smart host.  Since messages will be delivered via UUCP, the
attribute must specify a system known to your UUCP software. Please
refer to chapter~\ref{uucp} on making a site known to UUCP.


There's one option used in the above file that we haven't explained yet;
this is \keyword{uucp\_name}. The reason to use the option is this: By
default, \prog{smail} uses the value returned by \keyword{hostname(2)}
for UUCP-specific things such as the return path given in the
\keyword{From\_} header line. If your hostname is \emph{not} registered
with the UUCP mapping project, you should tell \prog{smail} to use your
fully qualified domain name instead.\footnote{
 The reason is this: Assume your hostname is \keyword{monad}, but is not
 registered in the maps. However, there is a site in the maps called
 \keyword{monad}, so every mail to \keyword{monad!root}, even sent from
 a direct UUCP neighbor of yours, will wind up on the other
 \keyword{monad}. This is a nuisance for everybody.
} This can be done by adding the \keyword{uucp\_name} option to the
\file{config} file.



There is another file in \smaillib, called \file{paths.sample}. It
is an example of what a \file{paths} file might look like. However, you
will not need one unless you have mail links to more than one site.
If you do, however, you will have to write one yourself, or generate one
from the Usenet maps. The \file{paths} file will be described later in
this chapter.

\index{smail@\prog{smail}!config file@\file{config} file|)}
\index{smail@\prog{smail}!UUCP|)}

\section{Setup for a LAN}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.lan}
\index{configuring!mail on a LAN|(}
\index{smail@\prog{smail}!on a LAN|(}

If you are running a site with two or more hosts connected by a LAN, you
will have to designate one host that handles your UUCP connection with
the outside world. Between the hosts on your LAN, you will most probably
want to exchange mail with SMTP over TCP/IP.  Assume we're back at the
Virtual Brewery again, and \host{vstout} is set up as the UUCP gateway.


\index{mailboxes!mounting via NFS}
\index{mail!site hiding}
\index{mail!on a LAN}
\index{LAN!mail}
In a networked environment, it is best to keep all user mailboxes on a
single file system, which is NFS-mounted on all other hosts. This allows
users to move from machine to machine, without having to move their mail
around (or even worse, check some three or four machines for
newly-arrived mail each morning). Therefore, you also want to make
sender addresses independent from the machine the mail was written on.
It is common practice to use the domain name all by itself in the sender
address, instead of a hostname.  Janet User, for example, would specify
\email{janet@vbrew.com} instead of \email{janet@vale.vbrew.com}.  We
will explain below how to make the server recognize the domain name as a
valid name for your site.


%% Probably mention IMAP as well
\index{Interactive Mail Access Protocol}
\index{Post Office Protocol}
\index{IMAP}
\index{POP}
A different way of keeping all mailboxes on a central host is to use
POP or IMAP.  POP stands for \emph{Post Office Protocol} and lets
users access their mailboxes over a simple TCP/IP conection.  IMAP,
the \emph{Interactive Mail Access Protocol}, is similar to POP, but
more general. Both clients and servers for IMAP and POP have been
ported to \linux, and are available from \host{sunsite.unc.edu} below
\file{/pub/Linux/system/Network}.


\subsection{Writing the Configuration Files}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{smail@\prog{smail}!handling mail for a domain}

The configuration for the Brewery works as follows: all hosts except the
mail server \host{vstout} itself route all outgoing mail to the server,
using smart host routing. \host{vstout} itself sends all outgoing mail
to the real smart host that routes all of the Brewery's mail; this host
is called \host{moria}.


The standard \file{config} file for all hosts other than \host{vstout}
looks like this:


\begin{tscreen}
\begin{verbatim}
#
# Our domain:
visible_domain=vbrew.com
#
# What we name ourselves
visible_name=vbrew.com
#
# Smart-host routing: via SMTP to vstout
smart_path=vstout
smart_transport=smtp
\end{verbatim}
\end{tscreen}


This is very similar to what we used for a UUCP-only site. The main
difference is that the transport used to send mail to the smart host
is, of course, SMTP. The \keyword{visible\_domain} attribute makes
\prog{smail} use the domain name instead of the local hostname on
all outgoing mail.


\index{configuring!mail gateway}
On the UUCP mail gateway \host{vstout}, the \file{config} file looks a
little different:


\begin{tscreen}
\begin{verbatim}
#
# Our hostnames:
hostnames=vbrew.com:vstout.vbrew.com:vstout
#
# What we name ourselves
visible_name=vbrew.com
#
# in the uucp world, we're known as vbrew.com
uucp_name=vbrew.com
#
# Smart transport: via uucp to moria
smart_path=moria
smart_transport=uux
#
# we're authoritative for our domain
auth_domains=vbrew.com
\end{verbatim}
\end{tscreen}


This \file{config} file uses a different scheme to tell \prog{smail}
what the local host is called.  Instead of giving it a list of domains
and letting it find the hostname with a system call, it specifies a list
explicitly.  The above list contains both the fully qualified and the
unqualified hostname, and the domain name all by itself. This makes
\prog{smail} recognize \email{janet@vbrew.com} as a local address, and
deliver the message to \email{janet}.


The \keyword{auth\_domains} variable names the domains for which
\host{vstout} is considered to be authoritative. That is, if
\prog{smail} receives any mail addressed to \var{host}\host{.vbrew.com}
where \var{host} does not name an existing local machine, it rejects the
message and returns it to the sender.  If this entry isn't present, any
such message will be sent to the smart-host, who will return it to
\host{vstout}, and so on until it is discarded for exceeding the maximum
hop count.



\subsection{Running \prog{smail}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{smail@\prog{smail}!SMTP|(}

First, you have to decide whether to run \prog{smail} as a separate
daemon, or whether to have \prog{inetd} manage the SMTP port and invoke
\prog{smail} only whenever an SMTP connection is requested from some
client. Usually, you will prefer daemon operation on the mail server,
because this loads the machine far less than spawning \prog{smail} over
and over again for each single connection. As the mail server also
delivers most incoming mail directly to the users, you will choose
\prog{inetd} operation on most other hosts.


\index{SMTP!service}
Whatever mode of operation you choose for each individual host,
you have to make sure you have the following entry in your
\file{/etc/services} file:


\begin{tscreen}
\begin{verbatim}
smtp            25/tcp          # Simple Mail Transfer Protocol
\end{verbatim}
\end{tscreen}


This defines the TCP port number that \prog{smail} should use for SMTP
conversations. 25 is the standard defined by the Assigned Numbers RFC.


When run in daemon mode, \prog{smail} will put itself in the background,
and wait for a connection to occur on the SMTP port. When a connection
occurs, it forks and conducts an SMTP conversation with the peer
process.  The \prog{smail} daemon is usually started by invoking it from
the \file{rc.inet2} script using the following command:


\begin{tscreen}
/usr/local/bin/smail -bd -q15m
\end{tscreen}


The \option{-bd} flag turns on daemon mode, and \option{-q15m} makes
it process whatever messages have accumulated in the message queue every
15 minutes.


\index{inetd@\prog{inetd}}
If you want to use \prog{inetd} instead, your \file{/etc/inetd.conf}
file should contain a line like this:


\begin{tscreen}
\begin{verbatim}
smtp    stream  tcp nowait  root  /usr/sbin/smtpd smtpd
\end{verbatim}
\end{tscreen}


\prog{smtpd} should be a symbolic link to the \prog{smail} binary.
Remember you have to make \prog{inetd} re-read \file{inetd.conf} by
sending it a \keyword{HUP} signal after making these changes.


Daemon mode and \prog{inetd} mode are mutually exclusive. If you run
\prog{smail} in deamon mode, you should make sure to comment out any
line in \file{inetd.conf} for the \keyword{smtp} service. Equivalently,
when having \prog{inetd} manage \prog{smail}, make sure that
\file{rc.inet2} does not start the \prog{smail} daemon.

\index{smail@\prog{smail}!SMTP|)}
\index{configuring!mail on a LAN|)}
\index{smail@\prog{smail}!on a LAN|)}


\section{If You Don't Get Through\ldots}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{smail@\prog{smail}!troubleshooting}
\index{smail@\prog{smail}!log files}

If something goes wrong with your installation, there are a number of
features that may help you to find what's at the root of the problem.
The first place to check are \prog{smail}'s log files. They are
kept in \smailspool\file{/log}, and are named \file{logfile}
and \file{paniclog}, respectively. The former lists all transactions,
while the latter is only for error messages related to configuration
errors and the like.


A typical entry in \file{logfile} looks like this:

\begin{tscreen}
\begin{verbatim}
04/24/94 07:12:04: [m0puwU8-00023UB] received
|            from: root
|         program: sendmail
|            size: 1468 bytes
04/24/94 07:12:04: [m0puwU8-00023UB] delivered
|             via: vstout.vbrew.com
|              to: root@vstout.vbrew.com
|         orig-to: root@vstout.vbrew.com
|          router: smart_host
|       transport: smtp
\end{verbatim}
\end{tscreen}

This shows that a message from \user{root} to
\email{root@vstout.vbrew.com} has been properly delivered to host
\host{vstout} over SMTP.


Messages \prog{smail} could not deliver generate a similar entry in
the log file, but with an error message instead of the \term{delivered}
part:

\begin{tscreen}
\begin{verbatim}
04/24/94 07:12:04: [m0puwU8-00023UB] received
|            from: root
|         program: sendmail
|            size: 1468 bytes
04/24/94 07:12:04: [m0puwU8-00023UB] root@vstout.vbrew.com ... deferred
 (ERR_148) transport smtp: connect: Connection refused
\end{verbatim}
\end{tscreen}


The above error is typical for a situation in which \prog{smail}
properly recognizes that the message should be delivered to
\host{vstout} but was not able to connect to the SMTP service on
\host{vstout}. If this happens, you either have a configuration problem,
or TCP support is missing from your \prog{smail} binaries.


\index{checking!smail configuration@\prog{smail} configuration}
This problem is not as uncommon as one might think. There have been
precompiled \prog{smail} binaries around, even in some \linux{}
distributions, without support for TCP/IP networking. If this is the
case for you, you have to compile \prog{smail} yourself. Having
installed \prog{smail}, you can check if it has TCP networking support
by telnetting to the SMTP port on your machine. A successful connect to
the SMTP server is shown below (your input is marked \var{like this}):


\begin{tscreen}
 \$ \var{telnet localhost smtp}         \\
 Trying 127.0.0.1...                    \\
 Connected to localhost.                \\
 Escape character is '\car]'.           \\
 220 monad.swb.de Smail3.1.28.1 \#6 ready at Sun, 23 Jan 94 19:26 MET   \\
 \var{QUIT}                             \\
 221 monad.swb.de closing connection
\end{tscreen}


If this test doesn't produce the SMTP banner (the line starting with
the 220 code), first make sure that your configuration is \emph{really}
correct before you go through compiling \prog{smail} yourself, which 
is described below.


If you encounter a problem with \prog{smail} that you are unable to
locate from the error message \prog{smail} generates, you may want to
turn on debugging messages. You can do this using the \option{-d} flag,
optionally followed by a number specifying the level of verbosity (you
may not have any space between the flag and the numerical argument).
\prog{smail} will then print a report of its operation to the screen,
which may give you more hints about what is going wrong.


{\bf [Don't know,\ldots Maybe people don't find this funny:]}
If nothing else helps, you may want to invoke \prog{smail} in Rogue mode
by giving the \option{-bR} option on the command line. The manpage says
on this option: ``Enter the hostile domain of giant mail messages, and
RFC standard scrolls. Attempt to make it down to protocol level 26 and
back.'' Although this option won't solve your problems, it may provide
you some comfort and consolation.\footnote{
  Don't use this if you're in a really bad mood.
}


\subsection{Compiling \prog{smail}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{smail@\prog{smail}!compiling}

If you know for sure that \prog{smail} is lacking TCP network support,
you have to get the source. It is probably included in your
distribution, if you got it via CD-ROM, otherwise you may get it from
the net via FTP.\footnote{
 If you bought this with a \linux{} distribution from a vendor, you are
 entitled to the source code ``for a nominal shipping charge'',
 according to \prog{smail}'s copying conditions.
}


When compiling \prog{smail}, you had best start with the set of
configuration files from Vince Skahan's \file{newspak} distribution. To
compile in the TCP networking driver, you have to set the
\keyword{DRIVER\_CONFIGURATION} macro in the \file{conf/EDITME} file to either
\keyword{bsd-network} or \keyword{arpa-network}.  The former is suitable for LAN
installations, but the Internet requires \keyword{arpa-network}.  The
difference between these two is that the latter has a special driver for
BIND service that is able to recognize MX records, which the former
doesn't.



\section{Mail Delivery Modes}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% To queue or not to queue, that's the question.                %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.queue}
\index{smail@\prog{smail}!delivery modes}
\index{smail@\prog{smail}!queuing mail}
\index{queuing mail}
\index{mail!queue|(}

As noted above, \prog{smail} is able to deliver messages immediately, or
queue them for later processing.  If you choose to queue messages,
\prog{smail} will store away all mail in the \file{messages} directory
below \smailspool. It will not process them until explicitly told so
(this is also called ``running the queue'').


You can select one of three delivery modes by setting the
\keyword{delivery\_mode} attribute in the \file{config} file to either
of \keyword{foreground}, \keyword{background}, or \keyword{queued}. These
select delivery in the foreground (immediate processing of incoming
messages), in the background, (message is delivered by a child of the
receiving process, with the parent process exiting immediately after
forking), and queued. Incoming mail will always be queued regardless
of this option if the boolean variable \keyword{queue\_only} is set
in the \file{config} file.


If you turn on queuing, you have to make sure the queues are
checked regularly; probably every 10 or 15 minutes.  If you run
\prog{smail} in daemon mode, you have to add the option \option{-q10m}
on the command line to process the queue every 10~minutes.
Alternatively, you can invoke \prog{runq} from \prog{cron} at these
intervals. \prog{runq} should be a link to \prog{smail}.


\index{smail@\prog{smail}!check mail queue}
\index{checking!mail queue}
You can display the current mail queue by invoking \prog{smail}
with the \option{-bp} option. Equivalently, you can make \prog{mailq}
a link to \prog{smail}, and invoke \prog{mailq}:

\begin{tscreen}
\begin{verbatim}
$ mailq -v
m0pvB1r-00023UB	From: root  (in /var/spool/smail/input)
                Date: Sun, 24 Apr 94 07:12 MET DST
                Args: -oem -oMP sendmail root@vstout.vbrew.com
Log of transactions:
 Xdefer: <root@vstout.vbrew.com> reason: (ERR_148) transport smtp:
 connect: Connection refused
\end{verbatim}
\end{tscreen}


This shows a single message sitting in the message queue. The
transaction log (which is only displayed if you give \prog{mailq} the
\option{-v} option) may give an additional reason why it is still
waiting for delivery.  If no attempt has been made yet to deliver the
message, no transaction log will be displayed.


\index{smail@\prog{smail}!run the queue}
Even when you don't use queuing, \prog{smail} will occasionally put
messages into the queue when it finds immediate delivery fails for a
transient reason. For SMTP connections, this may be an unreachable host;
but messages may also be deferred when the file system is found to be
full.  You should therefore put in a queue run every hour or so (using
\prog{runq}), else any deferred message will stick around the queue
forever.


\index{mail!queue|)}

% \section{Assigning Message Grades}
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \label{smail.grades}
% As explained in section~\ref{mail.grades}, messages can be assigned
% different service by giving certain tokens in the \mhdr{Precedence:}
% header field. \prog{smail} maps these precedence tokens to a spool
% grades, which is a single letter from 0-9, A-Z,
% and a-z, in decreasing order. If no \mhdr{Precedence:} field
% is present, or the token is not recognized, a default grade is assumed.
% 
% 
% When using UUCP, this grade is passed to \prog{uux} as the UUCP spool
% grade (see section~\ref{uucp.intro.grades}), which determines at what
% time the message may be transferred. \prog{smail} itself uses the grade
% when generating bounce messages for undeliverable mail. By default,
% the bounce message will contain the undeliverable message aling with the
% error notification; but messages with grades in the range a-m
% will only have the original header returned, and messages with a
% spool grade between n and z will be discarded alogether in
% case of an error.
% 
% 
% When you use so called \emph{method}-files (see the \prog{smail(5)}
% manual page for details), you can also use the message grade to
% assign different transports; for example, you could have messages
% with a spool grade of 9 or higher be delivered immediately,
% while others are spooled until the next UUCP connection is established.
% 
% 
% Now \prog{smail} permits you to assign spool grades to precedence tokens
% in whatever way you like. You can do this by setting the \keyword{grades}
% variable in \file{config}.
% 
% 
% This variable is assigned a string consisting of an alternating
% sequence of pecedence tokens and spool grades, which are separated
% by a single colon. The default value is
% 
% \begin{tscreen}
%  grades = special-delivery:9:air-mail:A:first-class:C:buld:a:junk:n
% \end{tscreen}
% 
% which assigns a grade of 9 to a message that has a
% precedence of \keyword{special-delivery}, and so on.
% 
% 
% The default spool grade may be set using the \keyword{spool\_grade}
% variable. The default is
% 
% \begin{tscreen}
%  spool\_grade = C
% \end{tscreen}
% 
% 

\section{Miscellaneous \prog{config} Options}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.options}
\index{smail@\prog{smail}!config file@\file{config} file}

There are quite a number of options you may set in the \file{config} file,
which, although useful, are not essential to running \prog{smail}, and
which we will not discuss here. Instead, we will only mention a
few that you might find a reason to use:


\begin{dispitems}
\ditem[\keyword{error\_copy\_postmaster}]
        \index{mail!postmaster}
        \index{smail@\prog{smail}!postmaster}
        \index{mail!bounce}
        If this boolean variable is set, any error will generate a
        message to the postmaster.  Usually, this is only done for
        errors that are due to a faulty configuration.  The variable can
        be turned on by putting it in the \file{config} file, preceded
        by a plus (\keyword{+}).

\ditem[\keyword{max\_hop\_count}]
        \index{smail@\prog{smail}!routing!avoid loops}
        \index{avoid mail routing loops}
        \index{routing!loop avoidance}
        If the hop count for a message (i.e. the number of hosts
        already traversed) equals or exceeds this number, attempts at
        remote delivery will result in an error message being returned
        to the sender. This is used to prevent messages from looping
        forever. The hop count is generally computed from the number
        of \keyword{Received:} fields in the mail header, but may also
        be set manually using the \option{-h} option on the
        command line.

        This variable defaults to 20.

\ditem[\keyword{postmaster}]
        \index{mail!postmaster}
        \index{smail@\prog{smail}!postmaster}
        The postmaster's address. If the address \email{Postmaster}
        cannot be resolved to a valid local address, then this
        is used as the last resort. The default is \email{root}.

\end{dispitems}



\section{Message Routing and Delivery}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Introduction to routers, directors, transport                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.delivery}
\index{smail@\prog{smail}!routing}

\prog{smail} splits up mail delivery into three different tasks,
the router, director, and transport module.


The router module resolves all remote addresses, determining to which
host the message should be sent to next, and which transport must be
used. Depending on the nature of the link, different transports
such as UUCP or SMTP may be used.


Local addresses are given to the director task which resolves any
forwarding or aliasing. For example, the address might be an alias or a
mailing list, or the user might want to forward her mail to another
address.  If the resulting address is remote, it is handed to the router
module for additional routing, otherwise it is assigned a transport for
local delivery. By far the most common case will be delivery to a
mailbox, but messages may also be piped into a command, or appended to
some arbitrary file.


The transport module, finally, is responsible for whatever method
of delivery has been chosen. It tries to deliver the message, and in
case of failure either generates a bounce message, or defers it for
a later retry.


\index{smail@\prog{smail}!transports@\file{transports}}
\index{smail@\prog{smail}!routers@\file{routers}}
\index{smail@\prog{smail}!directors@\file{directors}}
With \prog{smail}, you have much freedom in configuring these tasks.
For each of them, a number of drivers are available, from
which you can choose those you need. You describe them to \prog{smail}
in a couple of files, namely \file{routers}, \file{directors}, and
\file{transports}, located in \smaillib. If these files do not exist,
reasonable defaults are assumed that should be suitable for many sites
that either use SMTP or UUCP for transport. If you want to change
\prog{smail}'s routing policy, or modify a transport, you should get the
sample files from the \prog{smail} source distribution,\footnote{
  The default configuration files can be found in \file{samples/generic}
  below the source directory.
} copy the sample files to \smaillib, and modify them according to your
needs. Sample configuration files are also given in
Appendix~\ref{appendix.smail}.



\section{Routing Messages}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Routers & Directors                                           %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.routing}
\index{smail@\prog{smail}!routing|(}

When given a message, \prog{smail} first checks if the destination is
the local host, or a remote site.  If the target host address is one of
the local hostnames configured in \file{config}, the message is handed
to the director module. Otherwise, \prog{smail} hands the destination
address to a number of router drivers to find out which host to forward
a message to.  They can be described in the \file{routers} file; if this
file does not exist, a set of default routers are used.


The destination host is passed to all routers in turn, and the one
finding the most specific route is selected. Consider a message
addressed to \email{joe@foo.bar.com}. Then, one router might know a
default route for all hosts in the \host{bar.com} domain, while another
one has information for \host{foo.bar.com} itself. Since the latter is
more specific, it is chosen over the former. If there are two routers
that provide a ``best match'', the one coming first in the
\file{routers} file is chosen.


This router now specifies the transport to be used, for instance UUCP,
and generates a new destination address. The new address is passed to
the transport along with the host to forward the message to.  In the
above example, \prog{smail} might find out that \host{foo.bar.com} is to
be reached via UUCP using the path \email{ernie!bert}.  It will then
generate a new target of \email{bert!foo.bar.com!user}, and have the
UUCP transport use this as the envelope address to be passed to
\host{ernie}.


When using the default setup, the following routers are available:


\begin{itemize}
\item
        If the destination host address can be resolved using the
        \func{gethostbyname(3)} or \func{gethostbyaddr(3)} library call,
        the message will be delivered via SMTP. The only exception is if
        the address is found to refer to the local host, it is handed to
        the director module, too.


        \prog{smail} also recognizes IP~addresses written as dotted quad
        as a legal hostname, as long as they can be resolved through a
        \func{gethostbyaddr(3)} call.  For example,
        \email{scrooge@[149.76.12.4]} would be a valid although highly
        unusual mail address for \user{scrooge} on
        \host{quark.physics.groucho.edu}.


        If your machine is on the Internet, these routers are not what
        you are looking for, because they do not support MX records. See
        below for what to do in this case.

\item
        \index{smail@\prog{smail}!paths file@\file{paths} file}
        \index{smail@\prog{smail}!routing!UUCP}
        If \smaillib\file{/paths}, the pathalias database, exists,
        \prog{smail} will try to look up the target host (minus
        any trailing \host{.uucp}) in this file.
        Mail to an address matched by this router will be
        delivered using UUCP, using the path found in the database.

\item
        \index{smail@\prog{smail}!UUCP}
        The host address (minus any trailing \host{.uucp}) will be
        compared to the output of the \prog{uuname} command to check if
        the target host is in fact a UUCP neighbor. If this is the case,
        the message will be delivered using the UUCP transport.

\item
        If the address has not been matched by any of the above
        routers, it will be delivered to the smart host. The path
        to the smart host as well as the transport to be used are
        set in the \file{config} file.

\end{itemize}


These defaults work for many simple setups, but fail if routing
requirements get a little more complicated. If you are faced with any
of the problems discussed below, you will have to install your own
\file{routers} file to override the defaults. A sample \file{routers}
file you might start with is given in appendix~\ref{appendix.smail}.
Some \linux{} distributions also come with a set of configuration
files that are tailored to work around these difficulties.


\index{smail@\prog{smail}!routing!UUCP vs. SLIP}
\index{smail@\prog{smail}!and SLIP/PPP}
\index{smail@\prog{smail}!UUCP}
Probably the worst problems arise when your host lives in a dual
universe with both dialup IP and UUCP links. You will then have
hostnames in your \file{hosts} file that you only talk occasionally to
through your SLIP link, so \prog{smail} will attempt to deliver any mail
for these hosts via SMTP. This is usually not what you want, because even
if the SLIP link is activated regularly, SMTP is much slower than sending
the mail over UUCP. With the default setup, there's no way escaping
\prog{smail}.


You can avoid this problem by having \prog{smail} check the \file{paths}
file before querying the resolver, and put all hosts you want to force
UUCP delivery to into the \file{paths} file. If you don't want to send
any messages over SMTP \emph{ever}, you can also comment out the
resolver-based routers altogether.


\index{smail@\prog{smail}!routing!Internet}
Another problem is that the default setup doesn't provide for true
Internet mail routing, because the resolver-based router does not
evaluate MX records. To enable full support for Internet mail routing,
comment out this router, and uncomment the one that used BIND instead.
There are, however, \prog{smail} binaries included in some \linux{}
distributions that don't have BIND support compiled in. If you enable
BIND, but get a message in the \file{paniclog} file saying
``\term{router inet\_hosts: driver bind not found}'', then you have to
get the sources and recompile \prog{smail} (see section~\ref{smail.lan}
above).


Finally, it is not generally a good idea to use the \prog{uuname}
driver.  For one, it will generate a configuration error when you don't
have UUCP installed, because no \prog{uuname} command will be found. The
second is when you have more sites listed in your UUCP \file{Systems}
file than you actually have mail links with. These may be sites you only
exchange news with, or sites you occasionally download files from via
anonymous UUCP, but have no traffic with otherwise.


To work around the first problem, you can substitute a shell script for
\prog{uuname} which does a simple \prog{exit 0}.  The more general
solution is, however, to edit the \file{routers} file and remove
this driver altogether.



\subsection{The \file{paths} database}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Directors avaiable                                            %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.pathalias}
\index{smail@\prog{smail}!paths file@\file{paths} file}
\index{smail@\prog{smail}!routing!UUCP}
\index{smail@\prog{smail}!UUCP}

\prog{smail} expects to find the pathalias database in the \file{paths}
file below \smaillib. This file is optional, so if you don't want to
perform any pathalias routing at all, simply remove any existing
\file{paths} file.


\file{paths} must be a sorted ASCII file that contains entries which map
destination site names to UUCP bang paths. The file has to be sorted
because \prog{smail} uses a binary search for looking up a site.
Comments are not allowed in this file, and the site name must be
separated from the path using a TAB.  Pathalias databases are discussed
in somewhat greater detail in chapter~\ref{mail}.


If you generate this file by hand, you should make sure to include all
legal names for a site. For example, if a site is known by both a plain
UUCP name and a fully qualified domain name, you have to add an entry
for each of them.  The file can be sorted by piping it through the
\prog{sort(1)} command.


If your site is only a leaf site, however, then no \file{paths}
file should be necessary at all: just set up the smart host
attributes in your \file{config} file, and leave all routing to
your mail feed.


\index{smail@\prog{smail}!routing|)}

\section{Delivering Messages to Local Addresses}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Directors avaiable                                            %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.directors}
\index{smail@\prog{smail}!local addresses|(}

Most commonly, a local address is just a user's login name, in which case
the message is delivered to her mailbox, \smailboxdir\file{/\var{user}}.
Other cases include aliases and mailing list names, and mail forwarding
by the user. In these cases, the local address expands to a new list
of addresses, which may be either local or remote.


Apart from these ``normal'' addresses, \prog{smail} can handle other
types of local message destinations, like file names, and pipe commands.
These are not addresses in their own right, so you can't send mail
to, say, \email{/etc/passwd@vbrew.com}; they are only valid if they have 
been taken from forwarding or alias files.


\index{smail@\prog{smail}!directing mail to a file}
\index{mail!directing to a file}
\index{directing mail to a file}
A \emph{file name} is anything that begins with a slash (\file{/}) or a
tilde (\file{\tld}).  The latter refers to the user's home directory, and
is possible only if the filename was taken from a \file{.forward} file
or a forwarding entry in the mailbox (see below).  When delivering to a
file, \prog{smail} appends the messages to the file, creating it if
necessary.


\index{smail@\prog{smail}!feeding mail to a command}
\index{mail!feeding to a command}
\index{feeding mail to a command}
A \emph{pipe command} may be any \unix{} command preceded by the pipe
symbol (\term{|}). This causes \prog{smail} to hand the command to the
shell along with its arguments, but without the leading `\term{|}'.  The
message itself is fed to this command on standard input.


For example, to gate a mailing list into a local newsgroup,
you might use a shell script named \prog{gateit}, and set up
a local alias which delivers all messages from this mailing list
to the script using \keyword{"|gateit"}.


If the invocation contains white space, it has to be enclosed
in double quotes. Due to the security issues involved, care is taken not
to execute the command if the address has been obtained in a somewhat
dubious way (for example, if the alias file from which the address was
taken was writable by everyone).


% The environment passed to the child process consists
% of the \keyword{TZ} variable as obtained from the calling process,
% and the following variables defined by \prog{smail}:
% 
% 
% \begin{dispitems}
% \ditem[\tt SENDER]
%         contains the sender's address.
% \ditem[\keyword{BASENAME} and \keyword{SPOOL\_FILE}]
%         contain the base and file name of the spool file.
% \ditem[\keyword{GRADE} and \keyword{MESSAGE\_ID}]
%         contain the message grade and the message id, respectively.
% \ditem[\keyword{PATH} and \keyword{SHELL}]
%         contain ``\file{/bin:/usr/bin}'' and ``\file{/bin/sh}'', respectively.
% \ditem[\keyword{PRIMARY\_NAME}, \keyword{UUCP\_NAME}, and \keyword{VISIBLE\_NAME}]
%         contain the values of the corresponding variables as
%         defined in the \file{config} file.
% \end{dispitems}




\subsection{Local Users}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{smail@\prog{smail}!user mailbox}
\index{mailbox file}

The most common case for a local address is to denote a user's mailbox.
This mailbox is located in \smailboxdir{} and has the name of the user.
It is owned by her, with a group of \user{mail}, and has mode 660.  If it
does not exist, it is created by \prog{smail}.


Note that although \smailboxdir{} is currently the standard place to
put the mailbox files, some mail software may have different paths
compiled in, for example \file{/usr/spool/mail}. If delivery to users
on your machine fails consistently, you should try if it helps to make
this a symbolic link to \smailboxdir.


There are two addresses \prog{smail} requires to exist:
\user{MAILER-DAEMON} and \user{Postmaster}. When generating a bounce
message for an undeliverable mail, a carbon copy is sent to the
\user{postmaster} account for examination (in case this might be due to
a configuration problem).  The \user{MAILER-DAEMON} is used as the
sender's address on the bounce message.


If these addresses do not name valid accounts on your system,
\prog{smail} implicitly maps \user{MAILER-DAEMON} to \user{postmaser},
and \user{postmaster} to \user{root}, respectively. You should usually
override this by aliasing the \user{postmaster} account to whoever is
responsible for maintaining the mail software.



\subsection{Forwarding}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{smail@\prog{smail}!forwarding}
\index{mail!forwarding}
\index{forwarding!mail}

A user may redirect her mail by having it forwarded to an alternative
address using one of two methods supported by \prog{smail}.  One option
is to put


\begin{tscreen}
 Forward to \var{recipient},\ldots
\end{tscreen}


\noindent
in the first line of her mailbox file.  This will send all incoming mail
to the specified list of recipients. Alternatively, she might create
a \file{.forward} file in her home directory, which contains the
comma-separated list of recipients.  With this variety of forwarding,
all lines of the file are read and interpreted.


Note that any type of address may be used. Thus, a practical example
of a \file{.forward} file for vacations might be


\begin{tscreen}
\begin{verbatim}
janet, "|vacation"
\end{verbatim}
\end{tscreen}


The first address delivers the incoming message to \email{janet}'s
mailbox nevertheless, while the \prog{vacation} command returns a short
notification to the sender.


\subsection{Alias Files}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{aliases@\file{aliases}|(}
\index{smail@\prog{smail}!user aliases|(}
\index{mail!aliases|(}
\index{mail!forwarding}
\index{forwarding!mail}
\index{alias!mail}

\prog{smail} is able to handle alias files compatible with those known by
Berkeley's \prog{sendmail}. Entries in the alias file may have the form


\begin{tscreen}
 {\sl alias}: {\sl recipients}
\end{tscreen}


\var{recipients} is a comma-separated list of addresses that will be
substituted for the alias. The recipient list may be continued across
newlines if the next line begins with a TAB.


There is a special feature that allows \prog{smail} to handle mailing lists
from the alias file: if you specify ``\term{:include:}\var{filename}''
as recipient, \prog{smail} will read the file specified, and substitute
its contents as a list of recipients.


The main aliases file is \file{/usr/lib/aliases}. If you choose to make
this file world-writable, \prog{smail} wil not deliver any messages to
shell commands given in this file. A sample file is shown below:


\begin{tscreen}
\small
\begin{verbatim}
# vbrew.com /usr/lib/aliases file
hostmaster: janet
postmaster: janet
usenet: phil
# The development mailing list.
development: joe, sue, mark, biff
        /var/mail/log/development
owner-development: joe
# Announcements of general interest are mailed to all
# of the staff
announce: :include: /usr/lib/smail/staff,
        /var/mail/log/announce
owner-announce: root
# gate the foobar mailing list to a local newsgroup
ppp-list: "|/usr/local/lib/gateit local.lists.ppp"
\end{verbatim}
\end{tscreen}


If an error occurs while delivering to an address generated from the
\file{aliases} file, \prog{smail} will attempt to send a copy of the
error message to the ``alias owner''. For example, if delivery to
\email{biff} fails when delivering a message to the \email{development}
mailing list, a copy of the error message will be mailed to the sender,
as well as to \email{postmaster} and \email{owner-development}.  If the
owner address does not exist, no additional error message will be
generated.


When delivering to files or when invoking programs given in the
\file{aliases} file, \prog{smail} will become the \user{nobody} user to
avoid any security hassles. Especially when delivering to files, this
can be a real nuisance. In the file given above, for instance, the log
files must be owned and writable by \user{nobody}, or delivery to them
will fail.

\index{aliases@\file{aliases}|)}
\index{smail@\prog{smail}!user aliases|)}
\index{mail!aliases|)}


\subsection{Mailing Lists}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.director.mailing-lists}
\index{smail@\prog{smail}!mailing lists|}

Instead of using the \file{aliases} file, mailing lists may also be
managed by means of files in the \smaillib\file{/lists} directory. A
mailing list named \keyword{nag-bugs} is described by the file
\file{lists/nag-bugs}, which should contain the members' addresses,
separated by commas. The list may be given on multiple lines, with
comments being introduced by a hash sign.


For each mailing list, a user (or alias) named
\user{owner-}\var{listname} should exist; any errors occurring when
resolving an address are reported to this user. This address is also
used as the sender's address on all outgoing messages in the
\mhdr{Sender:} header field.

\index{smail@\prog{smail}!local addresses|)}


\section{UUCP-based Transports}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.uucp}
\index{smail@\prog{smail}!UUCP|(}

There are a number of transports compiled into \prog{smail} that utilize
the UUCP suite. In a UUCP environment, messages are usually passed on by
invoking \prog{rmail} on the next host, giving it the message on
standard input and the envelope address on the command line. On your
host, \prog{rmail} should be a link to the \prog{smail} command.


When handing a message to the UUCP transport, \prog{smail} converts the
target address to a UUCP bang path. For example, \email{user@host} will
be transformed to \email{host!user}. Any occurrence of the `\email{\%}'
address operator is preserved, so \email{user\%host@gateway} will become
\email{gateway!user\%host}. However, \prog{smail} will never generate
such addresses itself.


\index{smail@\prog{smail}!BSMTP}
Alternatively, \prog{smail} can send and receive BSMTP batches via UUCP.
With BSMTP, one or more messages are wrapped up in a single batch that
contains the commands the local mailer would issue if a real SMTP
connection had be established.  BSMTP is frequently used in
store-and-forward (e.g. UUCP-based) networks to save disk space.  The
sample \file{transports} file in appendix~\ref{appendix.smail} contains
a transport dubbed \keyword{bsmtp} that generates partial BSMTP batches
in a queue directory. They must be combined into the final batches
later, using a shell script that adds the appropriate \keyword{HELO} and
\keyword{QUIT} command.


To enable the \keyword{bsmtp} transport for specific UUCP links you
have to use so-called \emph{method} files (please refer to the
\prog{smail(5)} manual page for details).  If you have only one UUCP
link, and use the smart host router, you enable sending SMTP batches by
setting the \keyword{smart\_transport} configuration variable to
\keyword{bsmtp} instead of \keyword{uux}.


To receive SMTP batches over UUCP, you must make sure that you have the
unbatching command the remote site sends its batches to. If the remote
site uses \prog{smail}, too, you need to make \prog{rsmtp} a link to
\prog{smail}. If the remote site runs \prog{sendmail}, you should
additionally install a shell script named \file{/usr/bin/bsmtp} that
does a simple ``\prog{exec} \prog{rsmtp}'' (a symbolic link won't work).

\index{smail@\prog{smail}!UUCP|)}

\section{SMTP-based Transports}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.smtp}
\index{smail@\prog{smail}!SMTP|(}

\prog{smail} currently supports an SMTP driver to deliver mail over
TCP connections.\footnote{
 The authors call this support ``simple''. For a future version of
 \prog{smail}, they advertise a complete backend which will handle this
 more efficiently.
} It is capable of delivering a message to any number of addresses on
one single host, with the hostname being specified as either a fully
qualified domain name that can be resolved by the networking software,
or in dotted quad notation enclosed in square brackets.  Generally,
addresses resolved by any of the BIND, \func{gethostbyname(3)}, or
\func{gethostbyaddr(3)} router drivers will be delivered to the SMTP
transport.


The SMTP driver will attempt to connect to the remote host immediately
through the \keyword{smtp} port as listed in \file{/etc/services}.  If
it cannot be reached, or the connection times out, delivery will be
reattempted at a later time.


Delivery on the Internet requires that routes to the destination host be
specified in the \emph{route-addr} format described in
chapter~\ref{mail}, rather than as a bang path.\footnote{
  However, the use of routes in the Internet is discouraged altogether.
  Fully qualified domain names should be used instead.
} \prog{smail} will therefore transform \email{user\%host@gateway},
where \host{gateway} is reached via \email{host1!host2!host3}, into the
source-route address \email{<@host2,@host3:user\%host@gateway>} which
will be sent as the message's envelope address to \email{host1}.  To
enable these transformation (along with the built-in BIND driver), you
have to edit the entry for the \keyword{smtp} driver in the
\file{transports} file.  A sample \file{transports} file is given in
Appendix~\ref{appendix.smail}.

\index{smail@\prog{smail}!SMTP|)}

\section{Hostname Qualification}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% The qualify file                                              %
% Used for conversion of user@host into user@host.domain, if    %
% host is known.                                                %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{smail.qualify}
\index{hostname!catching unqualified}
\index{smail@\prog{smail}!unqualified hostnames}

Sometimes it is desirable to catch unqualified hostnames (i.e. those
that don't have a domain name) specified in sender or recipient
addresses, for example when gatewaying between two networks, where one
requires fully qualified domain names.  On an Internet-UUCP relay,
unqualifed hostnames should be mapped to the \host{uucp} domain by
default.  Other address modifications than these are questionable.


The \smaillib\file{/qualify} file tells \prog{smail} which domain names
to tack onto which hostnames.  Entries in the \file{qualify} file
consists of a hostname beginning in column one, followed by domain name.
Lines containing a hash sign as its first non-white character are
considered comments.  Entries are searched in the order they appear in.


If no \file{qualify} file exists, no hostname qualification is performed
at all.


A special hostname of \host{*} matches any hostnames, thus enabling you
to map all hosts not mentioned before into a default domain. It should
be used only as the last entry.


At the Virtual Brewery, all hosts have been set up to use fully
qualified domain names in the sender's addresses. Unqualified recipient
addresses are considered to be in the \host{uucp} domain, so only a
single entry in the \file{qualify} file is needed.


\begin{screen}
\small
\begin{verbatim}
# /usr/lib/smail/qualify, last changed Feb 12, 1994 by janet
#
*            uucp
\end{verbatim}
\end{screen}

% \section{Administration Tasks}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% What you have to do.                                          %
% Secure Routing.                                               %
% Postmaster.                                                   %
% cleaning up log files. setting up cron tasks. using maps.     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\index{smail@\prog{smail}|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                             %%
%%              E N D   O F   C H A P T E R                    %%
%%                                                             %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
